Team Walker Frontend

Next.js React TypeScript Tailwind CSS pnpm GitHub Actions Husky

프로젝트의 프론트엔드 리포지토리입니다.

📑 목차

🛠 기술 스택

Category Technology
Framework Next.js 16 (App Router), React 19
Language TypeScript 5
Auth Supabase Auth (@supabase/ssr)
State Management Zustand
Styling Tailwind CSS 4, Radix UI, Lucide React
API & Data Axios, Orval (API Code Generation), Zod
PWA @ducanh2912/next-pwa
Animation Framer Motion
Documentation Storybook
Testing Jest, React Testing Library, Playwright (E2E)
Package Manager pnpm
Linting & Formatting ESLint, Prettier, Stylelint, Husky, Commitlint

📂 프로젝트 구조

├── app/                  # Next.js App Router (Pages, API, Layouts)
│   ├── (auth)/           # 인증 관련 페이지 (Login, Callback 등)
│   ├── (main)/           # 메인 서비스 페이지 (Home, Bookmark, MyPage 등)
│   ├── api/              # API Route Handlers (Geocode 등)
│   ├── globals.css       # Global Styles
│   └── layout.tsx        # Root Layout
├── components/           # 재사용 가능한 UI 컴포넌트
│   ├── common/           # 공통 컴포넌트 (SplashScreen 등)
│   ├── home/             # 홈 화면 전용 컴포넌트
│   ├── layout/           # 레이아웃 관련 (Header, BottomNav)
│   └── ui/               # Shadcn UI (Base Components)
├── hooks/                # Custom React Hooks
├── lib/                  # 유틸리티 및 설정
│   ├── api/              # Axios Instance & API Clients
│   └── supabase/         # Supabase Client & Middleware Logic
├── store/                # Zustand State Stores
├── types/                # TypeScript Type Definitions (API, Model 등)
├── constants/            # 공통 상수 및 설정
├── __tests__/            # Unit & Integration Tests (Jest)
├── e2e/                  # End-to-End Tests (Playwright)
├── stories/              # Storybook Stories
└── public/               # Static Assets & PWA Manifest

🚀 시작하기

1. 패키지 설치

pnpm install

2. 환경 변수 설정

.env.example 파일을 .env로 복사하고, 필요한 환경 변수 값을 설정합니다.

cp .env.example .env

3. 개발 서버 실행

pnpm dev

브라우저에서 http://localhost:3000으로 접속해 확인하세요.

4. 테스트 실행

pnpm test

✨ 핵심 기능 (Features)

📲 Mobile PWA & UI

📝 협업 가이드

팀원들과 함께 사용할 협업 규칙 및 컨벤션입니다.

1. 브랜치 전략 (Git Flow)

Git Flow 전략을 기반으로 운영합니다.

브랜치 종류

브랜치 용도 직접 Push
main 배포 가능한 프로덕션 코드 ❌ 금지
develop 다음 배포를 위한 개발 브랜치 ❌ 금지 (PR만 가능)
feat/#이슈번호-기능명 기능 개발 ✅ 가능
fix/#이슈번호-버그명 버그 수정 ✅ 가능

브랜치 네이밍 예시

feat/#12-login-page
feat/#23-main-banner
fix/#15-header-alignment
fix/#34-api-error-handling

📌 작업 프로세스

1. 이슈(Issue) 생성
   ↓
2. develop 브랜치 최신화
   git pull origin develop
   ↓
3. 작업 브랜치 생성
   git checkout -b feat/#이슈번호-기능명
   ↓
4. 작업 및 커밋
   ↓
5. 원격 저장소 푸시
   git push origin feat/#이슈번호-기능명
   ↓
6. PR 생성 (작업 브랜치 → develop)

2. 커밋 컨벤션 (Conventional Commits)

⚠️ 중요: 자동화 도구(commitlint, husky)에 의해 커밋 메시지 규칙이 강제됩니다.

커밋 메시지 형식

type: subject

Type 종류

Type 설명 예시
feat 새로운 기능 추가 feat: implement login api
fix 버그 수정 fix: resolve db connection issue
docs 문서 수정 (README, 주석 등) docs: update readme installation guide
style 코드 포맷팅, 세미콜론 누락 등 (로직 변경 없음) style: format code with prettier
refactor 코드 리팩토링 (기능 변경 없음) refactor: simplify user validation logic
test 테스트 코드 추가/수정 test: add unit tests for auth service
chore 빌드 업무, 패키지 매니저 설정 등 chore: update dependencies
perf 성능 개선 perf: optimize database queries
ci CI 구성 파일 및 스크립트 변경 ci: update github actions workflow
init 프로젝트 초기 생성 init: create project structure
revert 커밋 되돌리기 revert: undo previous commit

커밋 단위 (Atomic Commit)

✅ DO

❌ DON'T

좋은 커밋 예시

✅ feat: add user login component
✅ fix: resolve api timeout error
✅ style: format code with prettier

나쁜 커밋 예시

❌ FEAT: add login (type을 대문자로 작성)
❌ feat:add login (공백 없음)
❌ add login (type 누락)
❌ feat: add login, fix header, update styles (여러 작업 혼재)

3. PR(Pull Request) 전략

PR 템플릿이 설정되어 있습니다. 내용을 충실히 작성해주세요.

PR 제목 형식

type: 요약 #이슈번호

예시: feat: 메인 배너 구현 #23

PR 작성 체크리스트

리뷰 & 병합 규칙

단계 내용
1차 리뷰 AI 코드 리뷰(Gemini Code Assist) 필수 진행
2차 리뷰 최소 1명 이상의 팀원 승인(Approve) 필요
리뷰 포인트 코드의 논리적 오류, 컨벤션 준수, 테스트 코드 작성 여부
병합 방식 Squash and Merge 권장 (커밋 히스토리 정리)

💡 Gemini AI Bot 활용 팁

4. 코딩 & 스타일 컨벤션

자동 검사 도구

네이밍 컨벤션

대상 규칙 예시
컴포넌트 PascalCase LoginButton.tsx, UserProfile.tsx
함수/변수 camelCase getUserData, isLoggedIn
상수 UPPER_SNAKE_CASE API_BASE_URL, MAX_RETRY_COUNT
파일/폴더 Next.js 규칙 page.tsx, layout.tsx

코드 작성 원칙

  1. 명확한 변수명 사용: 축약어보다는 의미 있는 이름
  2. 함수는 단일 책임: 하나의 함수는 하나의 역할만
  3. 주석은 Why, not What: 코드가 무엇을 하는지보다 왜 그렇게 했는지 설명
  4. Early Return 패턴 사용: 중첩 if문보다는 조기 반환

5. CI/CD (Github Actions)

자동 실행 작업

PR 생성 및 푸시 시 자동으로 다음 작업이 실행됩니다:

⚠️ 주의: 테스트를 통과하지 못하면 Merge가 제한됩니다.

Git Hooks (로컬 검사)

Husky와 lint-staged를 통해 커밋 전 자동 검사:

규칙 위반 시 커밋이 중단되므로, 에러 메시지를 확인하여 수정 후 재시도하세요.

6. 스프린트 및 통합 주기 (Sprint & Integration)

1주 단위 스프린트로 개발 및 배포를 진행합니다.

통합 방식

상시 통합 (Continuous Integration)

정기 배포 (End of Sprint)

스프린트 프로세스 (1주 단위 예시)

월요일 (Sprint Start)
  └─ PO가 할당한 백로그 확인 및 작업 시작
     ↓
월~목 (Development)
  └─ feat 브랜치 작업 → develop으로 지속적 병합
     ↓
금요일 오전 (Code Freeze)
  └─ 새로운 기능 병합 중단
  └─ QA (테스트 코드 통과 및 수동 점검)
  └─ 버그 수정
     ↓
금요일 오후 (Release)
  └─ QA 통과 후 main 브랜치 병합 및 배포

위 일정은 프로젝트 상황에 따라 유연하게 변경될 수 있습니다.

⚡️ 빠른 참조

자주 사용하는 Git 명령어

# 브랜치 생성 및 이동
git checkout -b feat/#이슈번호-기능명

# develop 브랜치 최신화
git pull origin develop

# 현재 브랜치를 develop 기준으로 리베이스
git rebase develop

# 커밋 후 푸시
git add .
git commit -m "feat: add login button"
git push origin feat/#이슈번호-기능명

# 브랜치 삭제 (병합 후)
git branch -d feat/#이슈번호-기능명

문제 해결

커밋이 안 될 때

  1. 린트 에러 확인: pnpm lint
  2. 포맷팅 자동 수정: pnpm format
  3. 커밋 메시지 형식 확인 (소문자, type: subject)

충돌(Conflict) 발생 시

  1. git pull origin develop로 최신 코드 받기
  2. 충돌 파일 수동 해결
  3. git add . 후 git commit
  4. git push

빌드 실패 시

  1. node_modules 삭제 후 재설치: rm -rf node_modules && pnpm install
  2. .next 폴더 삭제 후 재빌드: rm -rf .next && pnpm build
  3. 환경 변수 확인: .env 파일 존재 및 내용 확인